package com.youlai.boot.modules.distribution.service;

import com.youlai.boot.modules.tp.dto.query.DateRangeQuery;
import com.youlai.boot.modules.distribution.dto.response.*;

import jakarta.servlet.http.HttpServletResponse;
import java.util.List;

/**
 * 经销看板服务接口
 * 
 * @author xiheforever
 * @since 2025-06-05
 */
public interface DistributionDashboardService {

    /**
     * 获取实时数据
     * 
     * @return 实时数据
     */
    DistributionRealTimeDataVO getRealTimeData();

    /**
     * 获取概览指标
     * 
     * @param dateRange 日期范围查询参数
     * @return 概览指标
     */
    DistributionOverviewMetricsVO getOverviewMetrics(DateRangeQuery dateRange);

    /**
     * 获取品牌表现列表
     * 
     * @param query 查询参数
     * @return 品牌表现分页数据
     */
    BrandPerformancePageVO getBrandPerformanceList(BrandPerformanceQueryVO query);

    /**
     * 获取类目分析
     * 
     * @param dateRange 日期范围查询参数
     * @param categoryLevel 类目级别
     * @return 类目分析数据
     */
    CategoryAnalysisResponseVO getCategoryAnalysis(DateRangeQuery dateRange, Integer categoryLevel);

    /**
     * 获取经营模式分析
     * 
     * @param dateRange 日期范围查询参数
     * @return 经营模式分析数据
     */
    OperationModeAnalysisResponseVO getOperationModeAnalysis(DateRangeQuery dateRange);

    /**
     * 获取品牌排行
     * 
     * @param dateRange 日期范围查询参数
     * @param limit 排行数量限制
     * @return 品牌排行数据
     */
    BrandRankingResponseVO getBrandRanking(DateRangeQuery dateRange, Integer limit);

    /**
     * 获取成交金额趋势
     * 
     * @param dateRange 日期范围查询参数
     * @return 成交金额趋势数据
     */
    TrendDataResponseVO getAmountTrend(DateRangeQuery dateRange);

    /**
     * 获取品牌数量趋势
     * 
     * @param dateRange 日期范围查询参数
     * @return 品牌数量趋势数据
     */
    TrendDataResponseVO getBrandCountTrend(DateRangeQuery dateRange);

    /**
     * 获取转化率趋势
     * 
     * @param dateRange 日期范围查询参数
     * @return 转化率趋势数据
     */
    TrendDataResponseVO getConversionTrend(DateRangeQuery dateRange);

    /**
     * 获取看板完整数据
     * 
     * @param dateRange 日期范围查询参数
     * @return 看板完整数据
     */
    DistributionDashboardAllDataVO getAllData(DateRangeQuery dateRange);

    /**
     * 导出品牌表现数据
     * 
     * @param query 查询参数
     * @param response HTTP响应对象
     */
    void exportBrandPerformance(BrandPerformanceQueryVO query, HttpServletResponse response);

    /**
     * 获取一级类目选项列表
     * 
     * @return 一级类目选项列表
     */
    List<String> getFirstCategoryOptions();

    /**
     * 获取经营模式选项列表
     * 
     * @return 经营模式选项列表
     */
    List<String> getOperationModeOptions();

    /**
     * 获取品牌选项列表
     * 
     * @return 品牌选项列表
     */
    List<String> getBrandOptions();
} 